Today, we are announcing the availability of Credentials Fetcher integration with Amazon Elastic Container Service (Amazon ECS). This integration makes it easier for developers to implement Windows Authentication in Linux containers running on Amazon ECS using Microsoft Active Directory (AD) group Managed Service Account (gMSA). The Credentials Fetcher daemon allows containers running on Linux hosts to authenticate using gMSA credentials.

A gMSA is a managed domain account that provides automatic password management. While a typical AD account requires an IT administrator to manually set, rotate, and synchronize the password, gMSA passwords are automatically managed by the AD, including seamless synchronization across multiple clients. This type of account is ideal for containerized applications in Amazon ECS, because all instances of a task definition should have the same permissions, and the number of running instances can scale dynamically.

Prior to this release, workloads running on Amazon ECS using gMSA credentials had to run using Windows containers. Linux containers provide cost savings, increased uptime, and improved scalability – but workloads running in Linux containers had to use a solution, such as a “sidecar container”, that authenticated to the AD using credentials stored in AWS Secrets Manager. One disadvantage of this approach is that the sidecar container doesn’t automatically rotate or synchronize the AD account password. When the password changes in the AD, the container’s authentication fails because the stored credentials are no longer valid.

With today’s release, customers modernizing their applications by taking advantage of Linux containers, can now use Windows authentication via the Kerberos protocol with automatic password management. This gives customers the ability to deploy workloads that are secure, easy to manage, cost-efficient, and scalable.

To explore how the gMSA support for Linux containers on Amazon ECS works, you’ll use the following sample solution:

You‘ll deploy:

After deploying these components, you’ll generate a Credential Specification (CredSpec) file for the created gMSA account, and upload it to Parameter Store, a capability of AWS Systems Manager, where Credentials Fetcher retrieves it.

Finally, you’ll build and deploy a simple .NET Web application in a Linux container on Amazon ECS. The Web application is configured to use the Windows Integrated Security to securely connect to the database. Credentials Fetcher is responsible for obtaining the Kerberos ticket from the gMSA and provides it to the Linux container.

The sample solution uses the AWS Cloud Development Kit (AWS CDK) to provision cloud resources using TypeScript. The AWS CDK allows developers to build AWS infrastructure in a variety of familiar programming languages, including JavaScript, C#, Python, Java, and Go.

Prior to any production deployment, you should always consult with your local security team to review security controls and requirements based on your environment and security posture.

For the tutorial, you should have the following prerequisites:

To start, create a directory for the solution in your local computer. Clone this GitHub repository into the directory.

Open a terminal in the cdk directory of the cloned repository, replace {KEY_PAIR_NAME} with your Amazon EC2 key pair name, and run the following commands if you are using Bash:

If you are using PowerShell, then run the following commands:

This starts the deployment of three AWS CloudFormation stacks that contain the sample solution. The deployment takes around one hour to complete.

When the deployment completes, navigate to the AWS CloudFormation console. You should see something similar to the following image:

During the deployment, a security group, user, and gMSA are created in the AD. The user is a set as member of the security group, which is authorized to retrieve password from the gMSA. The AD user’s password is randomly generated, and stored in the secret with name:

In the following sections, you’ll explore how to configure Amazon ECS and Credentials Fetcher to use these AD principals in the web application.

As first step, it’s necessary to install Credentials Fetcher in Amazon ECS. To do this automatically for all Amazon ECS container instances, you need to update the User Data inside the Auto Scaling Group’s Launch Template/Configuration adding the following commands:

The sample solution already configures this for you, so you can move to the next section.

The CredSpec file is a JSON document, which contains metadata about the gMSA account that’s used within each container. Credentials Fetcher uses the CredSpec file to request a Kerberos ticket and then make it available to the container. The CredSpec file can only be generated in a Windows computer when logged in as an admin user of the AD.

To start the process of generating it, navigate to the AWS Secrets Manager Console and copy the value of the amazon-ecs-gmsa-linux/active-directory-administrator-password secret.

You can also get the secret value by running this command in the Bash terminal:

If you are using PowerShell, then you can get the secret value by running this command:

Next, navigate to the Amazon EC2 console, then select the instance named amazon-ecs-gmsa-linux-bastion/active-directory-management-instance.

Follow these instructions to connect to the instance using Remote Desktop. Use the username directory.amazon-ecs-gmsa-linux.com\admin, and the password you retrieved from Secrets Manager. (If you can’t log in, then the instance is still setting up the database and AD. Wait 10–15 minutes and try again.)

In the Remote Desktop session, open a PowerShell window and run the following command:

This command creates the CredSpec file and stores its minimized contents as a Systems Manager parameter, where Amazon ECS retrieves it. There’s nothing more to do in this Amazon EC2 instance, so you can sign out of the Remote Desktop session.

To retrieve the password from a gMSA, the Credentials Fetcher requires an identity to authenticate with the AD. There are two ways to define this identity. The first option is by joining the Linux host to the AD domain, and authorizing the computer principal, or a security group the computer is member of, to retrieve passwords from the gMSA.

To implement this option, you can automatically join the Amazon ECS container instances to the AD domain using Systems Manager associations and the seamless domain join for Linux. You also need to add the Computer principals to the authorized AD security group. Currently, there’s no available command on Linux to add members to an AD security group, so you need to do this through an Amazon EC2 Windows instance. This needs to happen every time a new Amazon ECS container instance is created.

As part of the sample solution, you’ll find a PowerShell script inside the AD management Amazon EC2 instance that‘ll add all Amazon ECS container instances in a cluster to the appropriate AD security group. You’ll find the script in the path C:\SampleConfig\Add-ECSContainerInstancesToADGroup.ps1. You need to pass as argument the name of the Amazon ECS’s ASG, which you’ll find in the ECSAutoScalingGroupName output of the amazon-ecs-gmsa-linux-infrastructure AWS CloudFormation stack.

The second option is to provide the credentials for an AD user authorized to retrieve password from the gMSA directly to the Credentials Fetcher. This is a simpler solution that avoids the need to join the Amazon ECS container instances to the domain altogether. This also eliminates the need to run commands every time a new Amazon ECS container instance is created.

To provide the AD user’ credentials to Credentials Fetcher, you need to store the principal’s username and password in an AWS Secrets Manager secret. This secret should use a username and password keys to store the information. Note that the Amazon ECS container instances should have permission to read the value of this secret. You then need to set the CREDENTIALS_FETCHER_SECRET_NAME_FOR_DOMAINLESS_GMSA environment variable inside each Amazon ECS container instance. You can do this by adding the following command to the User Data inside the Auto Scaling Group’s Launch Template/Configuration:

The sample solution deploys the first option by default. If you want to use the second option, then you need to set the environment variable DOMAIN_JOIN_ECS=0 and redeploy the solution with the command cdk deploy "*" --require-approval "never". Deploying the solution this way removes the AD domain join State Manager association and sets the previous environment variable in the User Data inside the Auto Scaling Group’s Launch Template/Configuration. You need to terminate the existing Amazon ECS container instances to apply the new environment variable.

You can now continue to the next section where you will build the .NET sample application.

In the sample repository, there’s an ASP.NET Core 6 application that connects to a table in the sample SQL Server database. This application helps you validate that the connection to SQL Server is indeed using Integrated Security. The solution file is located at /web-app/web-app.sln. Make sure that it builds successfully using Visual Studio, Visual Studio Code or the following Command Line Interface (CLI) command:

Once the application has built successfully, you need to build the Docker container and push it to Amazon ECR. To do this, navigate to the Amazon ECR console. Select the amazon-ecs-gmsa-linux/web-site repository, then select View push commands.

Follow the directions to tag and push your image to the Amazon ECR repository.

If you are building the application in a Mac computer with an Apple M1/M2 processor, then all containers will be arm64 by default. Credentials Fetcher only supports x86-64 containers, so to build an x86-64 container, you need to run the following command instead of the one shown in the dialog window:

docker buildx build --platform=linux/amd64 -t amazon-ecs-gmsa-linux/web-site .

Now that you have pushed the application container image into Amazon ECR, your next step is to configure the Amazon ECS task definition to support Windows Authentication with gMSA.

To enable gMSA support in your Amazon ECS task definition, you need to set the dockerSecurityOptions property with a link to your minimized CredSpec. The CredSpec can be stored in an Amazon Simple Storage Service (Amazon S3) bucket, a Parameter Store parameter, or on a local file accessible by container. If you chose Amazon Simple Storage Service (Amazon S3) or Parameter Store, then you must set the Amazon ECS task execution role property to an AWS Identity and Access Management (AWS IAM) role with permission to read the parameter or bucket. For more information, see the Amazon ECS documentation for Using gMSAs for Linux Containers.

In the sample solution, the Amazon ECS task definition will look like similar to the following:

To configure dockerSecurityOptions through the AWS Console, using the classic Amazon ECS experience, create a new task definition (or a new version of an existing definition). In the container definition, go to the Security section and under Docker security options add credentialspec: followed by the Amazon Resource Names (ARN) for the Parameter Store parameter, Amazon S3 bucket, or local file path where you stored the CredSpec file.

In the sample solution, this property is already configured, so you are ready to deploy the application and see it working.

To deploy the application, go back to the terminal you used to deploy the infrastructure. Run the following commands if you are using Bash:

Run the following commands if you are using PowerShell:

Once the deployment completes, look for the AWS CDK Output named like amazon-ecs-gmsa-linux-application.websiteec2serviceServiceURLXXXXXXXX and copy its value. Wait a few seconds for the container to start, then navigate to this URL. The Web application runs and authenticates to the AD using the gMSA.

The ASP.NET Core application configuration is identical to any other environment, including on-premises. The only particularity you need to keep in mind is that the SQL Server address in the connection string MUST be defined using the AD domain name. If you use an IP address or a different DNS name, then the authentication method defaults to Microsoft NTLM, which will fail.

There are two main types of errors you may encounter when deploying the sample solution. The first, and most simple, type of error is when there is an error connecting to SQL Server. To diagnose the problem, navigate to the Amazon ECS console, select your cluster name, then the service name, and finally select Logs. Here you’ll see the errors that the application logged.

The second type of error is when the Amazon ECS task cannot be launched successfully. These root cause of these error are usually found in the Credentials Fetcher. To explore Credential’s Fetcher logs, you need to connect to one Amazon ECS container Linux instance, and run the following command: sudo journalctl -u credentials-fetcher -e. The logs tell you more accurately what problem is preventing the launch of the task.

To avoid incurring future charges, delete the resources. You can use the cdk destroy command to delete the stack. Run this command in the terminal or PowerShell window:

Finally, manually delete the Amazon ECR repository and Amazon CloudWatch log group.

In this post, we showed you how to integrate Credentials Fetcher with Amazon ECS. This integration enables AWS customers to modernize applications to Linux containers while using Windows authentication via gMSA. gMSA authentication, previously only available on Windows containers, allows applications and services to authenticate against an AD without manually managing passwords. This reduces complexity and improves security by reducing the risk of a password leak.

The sample application in the post shows how to use gMSA to support Windows authentication in a .NET application running in a Linux container, while connecting to a SQL Server database. This pattern enables enterprises to run modern containerized workloads that unlock the cost savings, reliability, and scalability of Linux – without sacrificing the secure authentication provided by AD.